6 Cross-Referencing

Cross-referencing is the act of referring to an object in your document by a linked name (Cross References, n.d.). If you’ve read a text and come across sentences such as “See Figure 1” or “as shown in Table 3.2”, you’ve read sentences the incorporate cross-referencing. Multiple document systems will help you do cross-referencing including Microsoft Word, LaTeX, and Quarto. It is often best to let those systems handle cross-referencing rather than you attempt to do it by hand. The computer is pretty good (better than us) at the tedious aspect of keeping the number all sorted.

Using good cross-referencing practices helps to create a cohesive narrative that fully incorporates all of your elements. Further, this allows your document to becomes dynamically updatable and more reproducible. All of which feed into creating items that align with Open Science principles.

6.1 Setting Up Elements

The first thing that you have to do if you want to cross-reference elements is you have to make sure that each element you want is uniquely named. For Tables and Figures, this is where the label code chunk option comes into play. For code chunks, you’ll use the lst-label option.

For equations and section headings, you’ll make use of label at the immediate end that is enclosed in curly braces and starts with a hash sign. For example, this sub-section’s heading appears as

## Setting Up Elements {#sec-setElements}

in the Quarto document, where{#sec-setElements} is the label.

Notice that every name follows a similar naming convention: prefix-uniqueName. The prefix specifies the cross-reference type and is what Quarto uses to keep track of numbering and add key words. The dash, -, separates the prefix from the unique name. When coming up with unique names, be sure to follow good naming practices: no spaces, don’t start with numerals, and avoid special characters–including the underscore.

There are multiple prefix that are built into Quarto. The most common are

fig for Figures
tbl for Tables
sec for Sections (headings)
eq for Equations
lst for (Code) Listings

Using lst

The lst prefix for listing should only be used if you are going to be displaying raw code or want to name an (un-)ordered list (rare). If you are trying to make a table or plot, the lst prefix is not appropriate.

6.2 Making a Cross-Reference

Once you have the items created and appropriately named, you can then reference them in the body of your Quarto document by typing an at symbol, @, and then immediately following that by the label for the element you want to refer to. For example, @tbl-diamondsSummary and @fig-namesPlot will let me cross-reference Table 4.1 and Figure 5.1 respectively. That’s all there is to making a cross-reference.

Notice that you can cross-reference elements from different parts of the document (or chapters of the book) using this method. The only requirement is that the elements must be part of the same project and appropriately linked.